feat: add GraphQL subscriptions over SSE (G3) - #1592

Closes #1585. Part of #1581.

Stacked on #1591 (G2) → #1590 (G1) → #1589 (G0). Merge those first.

Summary

Subscriptions with graphql-sse in distinct connections mode, on core SSE (EventStreamRepresentation, EventStreamReader). WebSocket comes in G4.

// Server
graphql.getSubscriptionTransports().add(GraphqlTransport.SSE);

// Client
Publisher<ExecutionResult> ticks = client.subscribe("subscription { ticks }", null, null);

Server

• A request accepting text/event-stream (named explicitly; wildcards don't select it) gets an event stream: next events carrying results, then complete. Queries and mutations are one next; subscriptions are also accepted over GET when GET is enabled. Request errors are 400 with a JSON body, as in graphql-sse.
• Back-pressure: one result requested at a time, the next one after the event is written, so the connector's flow control reaches the publisher.
• Disconnects: a failed write cancels the subscription. Heartbeats (15 s by default, configurable or off) keep idle streams open through proxies and detect disconnected idle clients.
• An empty comment is sent first so that the response head goes out at once. Without it, an idle subscription with heartbeats off kept the client waiting for headers (about 30 s in tests).
• Limits: 64 active subscriptions per adapter (503 beyond), 1 MiB of queued bytes per subscription. The queue only grows when a publisher ignores demand or a result is huge; beyond the limit the stream ends with an error and the subscription is cancelled. The connector's server.maxEventStreams still applies.
• stop() ends the adapter's open streams (error + complete), so that the server connector shuts down gracefully instead of waiting for idle subscriptions.
• Publisher failures are logged; subscribers receive a generic message.

Client

• subscribe(String|Document, operationName, variables) returns a cold Publisher<ExecutionResult>. Each subscriber sends its own POST on its first demand, from a virtual thread that emits all signals (no concurrent onNext).
• Demand is honored; cancel() aborts the request (Request.abort()); request(n <= 0) signals IllegalArgumentException.
• Request errors (server 400, or local validation with setSchema) are published as a single result. Non-GraphQL responses, events above maxResponseBytes and streams ending without complete are a GraphqlTransportException.
• stop() fails open subscriptions with a GraphqlTransportException; the borrowed client keeps running.

Core findings

• EventStreamReader has no line or event size limit (BufferedReader.readLine). The client wraps the stream with a per-event byte budget (one 8 KiB read-ahead margin); a bounded reader in core would be better.
• EventStreamRepresentation does not commit the response head until the first event or heartbeat.

Validation

./mvnw -B verify -P default,test -pl org.restlet.ext.graphql: 47 tests, 0 failures; 93.8% instruction coverage (gate 80%); Spotless, SpotBugs, Javadoc, -Werror and dependency convergence pass.

New GraphqlSseTestCase (16 tests): wire format of next/complete; queries over SSE; JSON request errors; GET subscriptions and GET mutations rejected; SSE off unless enabled; client disconnect cancels a busy subscription; heartbeats detect a disconnected idle client; subscription cap; queued bytes limit; client demand (no result without demand), completion, cancellation aborting the server-side subscription, stop(), request errors as results (remote and local validation), transport errors (HTML 502, truncated stream, oversized event), invalid demand; configuration validation.

🤖 Generated with Claude Code